Add PHPCS linting for PHP blocks in feature files - #340

…der sniffs from feature PHP blocks

Extraction took a number of leading whitespace characters off every line
of a block and syncing put the indentation of the block's first line back,
which is only the same thing when that line is the least indented one. A
block whose opening tag sits deeper than the code below it drifted further
to the right on every `composer phpcbf`, and one mixing tabs and spaces
came back with one swapped for the other, both without a single sniff
having fired. Extraction now takes off the indentation prefix that all
lines of a block share, and syncing puts exactly that prefix back.

Extraction also counted a docstring opening with `<?php` as a PHP block
while syncing only accepted one belonging to a step creating a `.php`
file. A docstring stating an expectation about the contents of a file was
therefore checked, fixed, and then refused, which failed the run and threw
the fixes away. Only the step decides now: reformatting an expectation
would make it stop matching what it is checked against, so the analysis in
`phpstan-feature-files.php` keeps the second rule and the fixer does not.

Both scripts let the filesystem root through as an extraction target. The
check meant to catch it appends a separator to the target before comparing,
which never matches a root that already ends in one, so `remove_extracted_files()`
would have walked the whole filesystem removing every empty directory it
could. Roots are now rejected up front, and the walk refuses to start on
one even if a caller gets past that.

Also names the feature file and the line in the two messages reporting a
block that could not be synced, so it is possible to tell which one it was.

The root of this package was derived from `dirname "$0"`, but Composer
installs these scripts as a symlink in the vendor binary directory, where
that resolves to `vendor` instead. `vendor/utils/extract-feature-php.php`
does not exist, so the check was skipped in every package using the testing
framework and only ever ran here, where `bin` and `utils` are siblings.
The symlink is now resolved first, the way `run-phpstan-tests` already does.

PHPCS truncates a reported path from the left once it grows past the width
of the report, which happened before the temporary directory was rewritten
out of it and left findings pointing at `...N1dTe6Y/some/feature.feature`.
Passing `--basepath` reduces the paths to the part worth showing, so the
report needs a single anchored substitution and no longer depends on the
length of a path it does not control.

The list of sniffs that do not apply to a block was spelled out in both
scripts. A future edit to one of them would have had the fixer rewrite
feature files over something the check never reports, so the list moves to
`phpcs/feature-files.sh`, which both read. That also gets the fixer the
`--warning-severity=0` only the check was passing. A package replaces the
defaults by adding a `phpcs-feature-files.xml` ruleset to its root.

The blocks are left alone when a run is narrowed down to a path, as in
`composer phpcs -- src/`, since such an argument is about the files of the
package itself rather than about its feature files.

Adds a section alongside the one for the static analysis, covering which
docstrings are checked and why a docstring merely opening with `<?php` is
not among them, where the defaults live, and how a package replaces them.

The README is regenerated from the partials on push to main.

`extract-feature-php.php` and `phpstan-feature-files.php` each carried
their own copy of the checks deciding which docstrings hold a PHP block and
where a block may be extracted to, in the same namespace and byte for byte
the same. Nothing catches such a pair drifting apart: the two run as
separate processes, `utils` is not autoloaded, and the static analysis only
looks at `src` and `tests`. The copies had already started to diverge, with
a fix for an extraction target resolving to the filesystem root landing in
one of them first.

They move to `utils/feature-php-blocks.php`, which both scripts pull in
themselves. It stays out of the autoloader, as loading a set of functions
into every package using the framework buys nothing.

`remove_extracted_files()` takes the pattern matching the extracted file
names as an argument, since the two tools name their files differently, and
the manifest that only the analysis writes is removed by the analysis.

The loop walking a feature file for docstrings existed twice: as
`collect_blocks()` in the analysis and inlined in the extractor of the code
style check, which is where the two had already come to disagree about what
counts as a PHP block. The check needs the narrower rule, since it writes a
block back and reformatting an expectation about the contents of a file
would make it stop matching, while the analysis wants every block it can
read.

Rather than a flag deciding that inside the shared loop, a block now comes
back saying which rule recognised it and whether it brings its own opening
tag, and each tool takes it from there. That also drops the separate pass
the check made over a block to answer the second question.

The walk over the feature files of a directory is shared along with it. The
code style check gains the stable order the analysis already relied on.

Both tools took the indentation a block shares off its lines before handing
them to PHP_CodeSniffer or PHPStan, and each did it its own way. The
analysis removed a number of characters, namely the smallest number of
leading whitespace characters any line of the block carried, which is only
the same thing as removing the shared prefix while every line is indented
with the same characters. It now uses the same `get_common_indent()` the
code style check does.

For a well-formed docstring the two agree, as every line of a block then
starts with the indentation of the docstring, and the analysis of every
feature file in config-command, entity-command and scaffold-command comes
out byte for byte the same. They part ways over a line indented with a tab
where the rest of the block uses spaces: the old computation would take the
tab off one line and a single space off another, leaving the block with an
indentation it never had. Nothing is written back on this side, so unlike
the same defect on the code style side this was not corrupting anything,
but it is one implementation now rather than two, and the one that is left
cannot lose the distinction.